Where should Service Documentation live?

#1

I am working on transitioning our team to have full service ownership. The first step I took is to document one service, following service documentation guide.

A wiki page for this documentation and each project’s readme will be for lower-level documentation (how the code is organized, how to call the API, any extra details needed, etc).

The dilemma is what is the best practice for service documentation? Should it live on each service’s readme files, a new section in our wiki or a new “docs” local website that is focused only on service documentation (based on PD’s gihub)?

Thank you,
Fausto

#2

I most frequently see it within a wiki page or GitHub repository, and then linked back into the PagerDuty Service or added dynamically as new events come into PagerDuty. The goal is that it should be accessible on any device (eg cell phone) and by anyone on-call easily when paged at 3AM.

Doug

1 Like
#3

Thank you, I wasn’t taking into account that i should be easily accesible. I’ll keep in on our wiki, It’s more accessible than any other option.

Thank you for your reply!

Fausto

#4

Hello Fausto,

Here is some insight from another one of our advocates:

Here’s my take. It should live where ever the people who work and interact with that service live. If the audience is essentially engineers, then a README in the service repo makes the most sense. If the audience is a mix of engineers who live in repos and other stakeholders that don’t then a wiki or internal site makes the most sense.

I hope this also provides some insight to you.

Cheers,

1 Like
#5

Those are good point Tatiana. I think i’ll end up having High level service documenation, dependencies and SLAs on a wiki, and lower level documenation (how to install or deploy, how it uses data, how to call it, etc) in the readme.

Thank you!

#6

Sounds good Fausto, keep us posted for any furthe questions!

John